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ABOUT THIS CHAPTER 


This chapter describes the Operating System Event Manager, the part of the 
Operating System that reports low-level user actions such as mouse-button 
presses and keystrokes. Usually your application will find out about events by 
calling the Toolbox Event Manager, which calls the Operating System Event 
Manager for you, but in some situations you'll need to call the Operating System 
Event Manager directly. 


Note: All references to "the Event Manager" in this chapter refer to 
the Operating System Event Manager. 


You should already be familiar with the Toolbox Event Manager. 


Note: Constants and data types defined in the Operating System Event Manager 
are presented in detail in the Toolbox Event Manager chapter, since 
they're necessary for using that part of the Toolbox. They're also 
listed in the summary of this chapter. 
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ABOUT THE OPERATING SYSTEM EVENT MANAGER 


The Event Manager is the part of the Operating System that detects low-level, 
hardware-related events: mouse, keyboard, disk-inserted, device driver, and 
network events. It stores information about these events in the event queue and 
provides routines that access the queue (analogous to GetNextEvent and 
EventAvail in the Toolbox Event Manager). It also allows your application to 
post its own events into the event queue. Like the Toolbox Event Manager, the 
Operating System Event Manager returns a null event if it has no other events to 
report. 


The Toolbox Event Manager calls the Operating System Event Manager to retrieve 
events from the event queue; in addition, it reports activate and update events, 
which aren't kept in the queue. It's extremely unusual for an application not to 
have to know about activate and update events, so usually you'll call the 
Toolbox Event Manager to get events. 


A new routine, PPostEvent, posts application-defined events into the event queue 
and returns a pointer to the created queue element. 


The Operating System Event Manager also lets you: 
* remove events from the event queue 


e set the system event mask, to control which types of events get 
posted into the queue 
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USING THE OPERATING SYSTEM EVENT MANAGER 


If you're using application-defined events in your program, you'll need to call 
the Operating System Event Manager function PostEvent to post them into the 
event queue. This function is sometimes also useful for reposting events that 
you've removed from the event queue with GetNextEvent. 


In some situations you may want to remove from the event queue some or all 
events of a certain type or types. You can do this with the procedure 
FlushEvents. A common use of FlushEvents is to get rid of any stray events left 
over from before your application started up. 


You'll probably never call the other Operating System Event Manager routines: 
GetOSEvent, which gets an event from the event queue, removing it from the queue 
in the process; OSEventAvail, for looking at an event without dequeueing it; and 
SetEventMask, which changes the setting of the system event mask. 
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OPERATING SYSTEM EVENT MANAGER ROUTINES 


Posting and Removing Events 
FUNCTION PostEvent (eventCode: INTEGER; eventMsg: LONGINT) : OSErr; 


Trap macro —PostEvent 
On entry AQ: eventCode (word) 

DO: eventMsg (long word) 
On exit DO: result code (word) 


PostEvent places in the event queue an event of the type designated by 
eventCode, with the event message specified by eventMsg and with the current 
time, mouse location, and state of the modifier keys and mouse button. It 
returns a result code (of type OSErr, defined as INTEGER in the Operating System 
Utilities) equal to one of the following predefined constants: 


CONST noErr 
evtNotEnb 


0; {no error (event posted) } 
1; {event type not designated in system event mask} 


Warning: Be very careful when posting any events other than your own 
application-defined events into the queue; attempting to post an 
activate or update event, for example, will interfere with the 
internal operation of the Toolbox Event Manager, since such events 
aren't normally placed in the queue at all. 


Warning: If you use PostEvent to repost an event, remember that the event 
time, location, and state of the modifier keys and mouse button 
will all be changed from their values when the event was originally 
posted, possibly altering the meaning of the event. 


FUNCTION PPostEvent (eventCode: INTEGER; eventMsg: LONGINT; 
VAR gEl: EvQElPtr) : OSErr); 


Trap macro —PPostEvent 
On entry AQ: eventCode (word) 
DO: eventMsg (long word) 
On exit AQ: pointer to event queue entry 


PPostEvent is identical to PostEvent except that it returns a pointer to the 
created queue entry. 


PROCEDURE FlushEvents (eventMask,stopMask: INTEGER); 


Trap macro _FlushEvents 


On entry DO: low-order word: eventMask 
high-order word: stopMask 
On exit DO: 0 or event code (word) 


FlushEvents removes events from the event queue as specified by the given event 
masks. It removes all events of the type or types specified by eventMask, up to 


@ SpInside Macintosh * Version 1.0 * November 1989 * Apple Computer 
THE OPERATING SYSTEM EVENT MANAGER e 5 of 13 


but not including the first event of any type specified by stopMask; if the 
event queue doesn't contain any events of the types specified by eventMask, it 
does nothing. To remove all events specified by eventMask, use a stopMask value 
of 0. 


At the beginning of your application, it's usually a good idea to call 
FlushEvents(everyEvent,@) to empty the event queue of any stray events that may 
have been left lying around, such as unprocessed keystrokes typed to the Finder. 


Assembly-language note: On exit from this routine, DO contains 0 if all 
events were removed from the queue or, if not, an 
event code specifying the type of event that caused 
the removal process to stop. 


Accessing Events 


FUNCTION GetOSEvent (eventMask: INTEGER; 
VAR theEvent: EventRecord) : BOOLEAN; 


Trap macro _GetOSEvent 


On entry AQ: pointer to event record theEvent 
DO: eventMask (word) 
On exit DO: O if non-null event returned, or —1 if null event 


returned (byte) 


GetOSEvent returns the next available event of a specified type or types and 
removes it from the event queue. The event is returned as the value of the 
parameter theEvent. The eventMask parameter specifies which event types are of 
interest. GetOSEvent will return the next available event of any type designated 
by the mask. If no event of any of the designated types is available, GetOSEvent 
returns a null event and a function result of FALSE; otherwise it returns TRUE. 


Note: Unlike the Toolbox Event Manager function GetNextEvent, GetOSEvent 
doesn't call the Desk Manager to see whether the system wants to 
intercept and respond to the event; nor does it perform GetNextEvent's 
processing of the alarm and Command-Shift-number combinations. 


FUNCTION OSEventAvail (eventMask: INTEGER; 
VAR theEvent: EventRecord) : BOOLEAN; 


Trap macro OSEventAvail 


On entry AQ: pointer to event record theEvent 
DO: eventMask (word) 
On exit DO: O if non-null event returned, or —1 if null event 


returned (byte) 


OSEventAvail works exactly the same as GetOSEvent (above) except that it 
doesn't remove the event from the event queue. 


Note: An event returned by OSEventAvail will not be accessible later if 
in the meantime the queue becomes full and the event is discarded 
from it; since the events discarded are always the oldest ones in 
the queue, however, this will happen only in an unusually busy 
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environment. 


Setting the System Event Mask 
PROCEDURE SetEventMask (theMask: INTEGER); [Not in ROM] 


SetEventMask sets the system event mask to the specified event mask. The 
Operating System Event Manager will post only those event types that correspond 
to bits set in the mask. (As usual, it will not post activate and update events, 
which are generated by the Window Manager and not stored in the event queue.) 
The system event mask is initially set to post all except key-up events. 


Warning: Because desk accessories may rely on receiving certain types of 
events, your application shouldn't set the system event mask to 
prevent any additional types (besides key-up) from being posted. 
You should use SetEventMask only to enable key-up events in the 
unusual case that your application needs to respond to them. 


Assembly-language note: The system event mask is available to assembly- 
language programmers in the global variable SysEvtMask. 
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STRUCTURE OF THE EVENT QUEUE 


The event queue is a standard Macintosh Operating System queue, as described in 
the Operating System Utilities chapter. Most programmers will never need to 
access the event queue directly; some advanced programmers, though, may need to 
do so for special purposes. 


Each entry in the event queue contains information about an event: 


TYPE EvQEl = RECORD 


qLink: QElemPtr; {next queue entry} 
qType: INTEGER; {queue type} 
evtQwhat: INTEGER; {event code} 
evtQMessage: LONGINT; {event message} 
evtQwhen: LONGINT; {ticks since startup} 
evtQwhere: Point; {mouse location} 
evtQModifiers: INTEGER {modifier flags} 

END; 


QLink points to the next entry in the queue, and qlype indicates the queue type, 
which must be ORD(evType). The remaining five fields of the event queue entry 
contain exactly the same information about the event as do the fields of the 
event record for that event; see the Toolbox Event Manager chapter for a 
detailed description of the contents of these fields. 


You can get a pointer to the header of the event queue by calling the Operating 
System Event Manager function GetEvQHdr. 


FUNCTION GetEvQHdr : QHdrPtr; [Not in ROM] 
GetEvQHdr returns a pointer to the header of the event queue. 


Assembly-language note: The global variable EventQueue contains the 
header of the event queue. 
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SUMMARY OF THE OPERATING SYSTEM EVENT MANAGER 


Constants 
CONST 


{ Event codes } 


nullEvent = 0; {null} 

mouseDown =“ ]s {mouse- down} 

mouseUp = 2; {mouse-up} 

keyDown = 3% {key -down} 

keyUp = 4; {key -up} 

autoKey =" 5s f{auto-key} 

updateEvt = 6; {update; Toolbox only} 
diskEvt a7 {disk-inserted} 
activateEvt = 8; factivate; Toolbox only} 
networkEvt = 10; {network} 

driverEvt = 11; {device driver} 
applEvt = 12; {application-defined} 
app2Evt = 13; {application-defined} 
app3Evt = 14; {application-defined} 
app4Evt = 15; {application-defined} 


{ Masks for keyboard event message } 


charCodeMask 
keyCodeMask 


$OQ00000FF; {character code} 
$0000FFOO; {key code} 


{ Masks for forming event mask } 


mDownMask = 25 {mouse -down} 

mUpMask = 4; {mouse-up} 
keyDownMask = 8; {key -down} 

keyUpMask = 16; {key-up} 

autoKeyMask = 32; f{auto-key} 

updateMask = 64; {update} 

diskMask = 128; {disk-inserted} 
activMask = 256; {activate} 
networkMask = 1024; {network} 

driverMask = 2048; {device driver} 
app1Mask = 4096; f{application-defined} 
app2Mask = 8192; {application-defined} 
app3Mask = 16384; {application-defined} 
app4Mask = -32768; {application-defined} 
everyEvent = -1; {all event types} 


{ Modifier flags in event record } 


activeFlag 
btnState 


1; {set if window being activated} 
128; {set if mouse button up} 
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cmdKey = 256; {set if Command key down} 
shiftKey = 512; {set if Shift key down} 
alphaLock = 1024; {set if Caps Lock key down} 
optionKey = 2048; {set if Option key down} 


{ Result codes returned by PostEvent } 


noErr = 0; {no error (event posted) } 
evtNotEnb = 1; {event type not designated in system event mask} 
Data Types 
TYPE 
EventRecord = RECORD 
what: INTEGER; {event code} 
message: LONGINT; {event message} 
when: LONGINT; {ticks since startup} 
where: Point; {mouse location} 
modifiers: INTEGER {modifier flags} 
END; 
EvQEl = RECORD 
qLink: QElemPtr; {next queue entry} 
qType: INTEGER; {queue type} 
evtQwhat: INTEGER; {event code} 
evtQMessage: LONGINT; {event message} 
evtQWhen: LONGINT; {ticks since startup} 
evtQwhere: Point; {mouse location} 
evtQModifiers: INTEGER {modifier flags} 
END; 


Routines 
Posting and Removing Events 
FUNCTION PostEvent (eventCode: INTEGER; eventMsg: LONGINT) : OSErr; 
FUNCTION PPostEvent (eventCode: INTEGER; eventMsg: LONGINT; 
VAR gElPtr: EvQEl) : OSErr); 
PROCEDURE FlushEvents (eventMask,stopMask: INTEGER); 
Accessing Events 
FUNCTION GetOSEvent (eventMask: INTEGER; 
VAR theEvent: EventRecord) : BOOLEAN; 
FUNCTION OSEventAvail (eventMask: INTEGER; 
VAR theEvent: EventRecord) : BOOLEAN; 
Setting the System Event Mask 


PROCEDURE SetEventMask (theMask: INTEGER); [Not in ROM] 
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Directly Accessing the Event Queue 


FUNCTION GetEvQHdr : QHdrPtr; [Not in ROM] 


Assembly-Language Information 
Constants 


; Event codes 


nullEvt . EQU 0 snull 

mButDwnEvt . EQU 1 ;mouse-down 

mButUpEvt .EQU 2 ;mouse-up 

keyDwnEvt . EQU 3 ; key-down 

keyUpEvt . EQU 4 ;key-up 

autoKeyEvt .EQU 5 ;auto-key 

updatEvt . EQU 6 ;update; Toolbox only 
diskInsertEvt .EQU 7 ;disk- inserted 
activateEvt . EQU 8 ;activate; Toolbox only 
networkEvt .EQU 10 ;network 

ioDrvrEvt .EQU 11 ;device driver 
applEvt . EQU 12 ;application-defined 
app2Evt . EQU 13 ;application-defined 
app3Evt .EQU 14 ;application-defined 
app4Evt . EQU 15 ;applLication-defined 


; Modifier flags in event record 


activeFlag .EQU 0 ;set if window being activated 
btnState . EQU 2 ;set if mouse button up 

cmdKey . EQU 3 ;set if Command key down 
shiftKey .EQU 4 ;set if Shift key down 
alphaLock .EQU 5 ;set if Caps Lock key down 
optionKey .EQU 6 ;set if Option key down 


; Result codes returned by PostEvent 


noErr .EQU 0 ;no error (event posted) 
evtNotEnb .EQU 1 ;event type not designated in system event mask 


Event Record Data Structure 


evtNum Event code (word) 

evtMessage Event message (long) 

evtTicks Ticks since startup (long) 
evtMouse Mouse location (point; long) 
evtMeta State of modifier keys (byte) 
evtMBut State of mouse button (byte) 


evtBlkSize Size in bytes of event record 
Event Queue Entry Data Structure 


qLink Pointer to next queue entry 
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qType Queue type (word) 


evtQwhat Event code (word) 

evtQMessage Event message (long) 

evtQWhen Ticks since startup (long) 

evtQWhere Mouse location (point; long) 

evtQMeta State of modifier keys (byte) 

evtQMBut State of mouse button (byte) 

evtQBlLkSize Size in bytes of event queue entry 

Routines 

Trap macro On entry On exit 

_PostEvent AO: eventCode (word) DO: result code (word) 
DO: eventMsg (long) 

_PPostEvent AO: eventCode (word) AQ: ptr to event queue entry 
DO: eventMsg (long) 

_FlushEvents DO: low word: eventMask DO: 0 or event code (word) 

high word: stopMask 
_GetOSEvent AO: ptr to event record DO: O if non-null event, 
and theEvent —1 if null event (byte) 
_OSEventAvail DO: eventMask (word) 
Variables 


SysEvtMask System event mask (word) 
EventQueue Event queue header (10 bytes) 
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Further Reference: 


Toolbox Event Manager 
Technical Note #202, Resetting the Event Mask 


END OF DOCUMENT 
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